As this is highly coupled with body_format_string and that is optional, would it make sense to move both to an internal message?

done.

Does this require a JSON-body? I may have missed it, but this seems to be a generic transform, and doesn't require JSON-body to be sent.

JSON body is required. We have documented it that only JSON body is supported for now.

the whole body will be used

FWIW this might cause the headermap to go over the limit, and may be an attack vector, but as this filter doesn't have a security posture, it might be ok.

Also it would be good to clarify whether using this filter implies that all requests/responses are buffered, even if headers_mutations are defined without referencing RQ/RS_BODY. If there's a need to support both buffering and streaming modes, consider adding an enum field specifying the mode (and maybe only support one for now).

At next few weeks, I will try to support the event stream for the response. We will handle it as stream for that. But for JSON request/response, buffering always be used.

thoughts on using JSONPatch semantics here ?
https://jsonpatch.com
its used in Envoy Gateway API to edit xDS https://gateway.envoyproxy.io/docs/tasks/extensibility/envoy-patch-policy/#customize-response

SGTM. But it's will have big effect to the current implementation. I will update the API to keep the patch mode as enum and then we can support it in the future.

Related but not tied / blocker to this PR, do you have some insights for the streaming JSON parser support without waiting for the whole body once we get the enough data. I think the current nlohmann lib doesn't quite support it, and we could need some SAX style approach.

Maybe rapidJson could help? But we removed that because suggestions from google. 🤣

Do you think this needs to also address HTTP trailers case?
(I'm not saying to add it now, but there may need to be a config knob in the future that decides what needs to be buffered before sending it down/up the stream. I believe this may be in the "Transformation" message).

SGTM and make sense. Let's the future requirement/issue to tell us!

I wonder if there should just be a JsonTransform filter here, instead of something generic. The reason I bring this up is because the transformations seem to be highly coupled with JSON bodies. (this is a discussion and not a a call for action).
WDYT?

It's actually depends the feedback from the users and community, I personally hope this filter could handle various content type like plain text or url form by extend other fields in this filter.
JSON is supported first is because that the JSON is used widely for now in open API and AI related things. In addition, for the response, we need to support event stream to support AI traffic.

Will the headers be blocked until the body is buffered even if headers_mutations isn't configured?

For now, yes for simplification of the code. But this is good point that could be optimized.

Hmmm, it will require the decodeData to handle the continue or stop of decodeHeaders correctly. Seems it's not deserved to optimize because the additional complexity 🤔 The filter will not be performant anyway because the body processing.

I understand that this is an implementation issue, but I think it should be spelled clearly in a note above (example: buffering of the entire request headers and body will always happen on a request even if only headers are transformed).

Sure.

I'm a bit confused here. This field type is SubstitutionFormatString which by the name suggests that there will be a substitution. However, the action can either be MERGE or REPLACE. Is the MERGE essentially a substitute? If so, what is REPLACE in this case?

The Substitution in SubstitutionFormatString is means the substitution formatter will be used in the format string. For example, in the final generated output, %REQ(xxx)% in the format string will be substituted by the actual header value.

And the action is used to indicate how to handle the final generated output of the body_format and the original body content.

I will add some more comment to make it more clear.

Do you see a case for multiple body transformations?

Nope. This is a one time logic. We will generate a new body based on the body_format and then the new body will replace or be merge into original body content.
If multiple phase transformations is necessary, the users could configure multiple transform filters in the filter chain anyway. 🤔

I guess the same can be said about headers, but I agree that headers are more likely to have multiple transformations (one for each header key).

I guess the same can be said about headers, but I agree that headers are more likely to have multiple transformations (one for each header key).

I understand that this is an implementation issue, but I think it should be spelled clearly in a note above (example: buffering of the entire request headers and body will always happen on a request even if only headers are transformed).